home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2005 October / PCWOCT05.iso / Software / FromTheMag / XAMPP 1.4.14 / xampp-win32-1.4.14-installer.exe / xampp / php / pear / docs / tidy / .tmpREADME < prev    next >
Text File  |  2004-03-24  |  6KB  |  123 lines
  1.  
  2. README FOR ext/tidy by John Coggeshall <john@php.net>
  3.  
  4. Tidy Version: 0.7b
  5.  
  6. Tidy is an extension based on Libtidy (http://tidy.sf.net/) and allows a PHP developer
  7. to clean, repair, and traverse HTML, XHTML, and XML documents -- including ones with
  8. embedded scripting languages such as PHP or ASP within them using OO constructs.
  9.  
  10. ---------------------------------------------------------------------------------------
  11. !! Important Note !!
  12. ---------------------------------------------------------------------------------------
  13. At this time libtidy has a small memory leak inside the ParseConfigFileEnc() function
  14. used to load configuration from a file. If you intend to use this functionality apply
  15. the "libtidy.txt" patch (cd tidy/src/; patch -p0 < libtidy.txt) to libtidy sources and
  16. then recompile libtidy.
  17. ---------------------------------------------------------------------------------------
  18.  
  19. The Tidy extension has two separate APIs, one for general parsing, cleaning, and
  20. repairing and another for document traversal. The general API is provided below:
  21.  
  22.   tidy_create()                     Reinitialize the tidy engine
  23.   tidy_parse_file($file)        Parse the document stored in $file
  24.   tidy_parse_string($str)            Parse the string stored in $str
  25.   
  26.   tidy_clean_repair()               Clean and repair the document
  27.   tidy_diagnose()                Diagnose a parsed document
  28.   
  29.   tidy_setopt($opt, $val)           Set a configuration option $opt to $val
  30.   tidy_getopt($opt)                Retrieve a configuration option
  31.   
  32.     ** note: $opt is a string representing the option. Although no formal
  33.     documentation yet exists for PHP, you can find a description of many
  34.     of them at http://www.w3.org/People/Raggett/tidy/ and a list of supported
  35.     options in the phpinfo(); output**
  36.   
  37.   tidy_get_output()                 Return the cleaned tidy HTML as a string
  38.   tidy_get_error_buffer()           Return a log of the errors and warnings
  39.                                     returned by tidy
  40.   
  41.   tidy_get_release()                Return the Libtidy release date
  42.   tidy_get_status()                 Return the status of the document
  43.   tidy_get_html_ver()               Return the major HTML version detected for
  44.                                     the document;
  45.                                     
  46.   tidy_is_xhtml()                   Determines if the document is XHTML
  47.   tidy_is_xml()                     Determines if the document is a generic XML
  48.   
  49.   tidy_error_count()                Returns the number of errors in the document
  50.   tidy_warning_count()              Returns the number of warnings in the document
  51.   tidy_access_count()               Returns the number of accessibility-related
  52.                                     warnings in the document.
  53.   tidy_config_count()               Returns the number of configuration errors found
  54.   
  55.   tidy_load_config($file)           Loads the specified configuration file
  56.   tidY_load_config_enc($file,
  57.                        $enc)        Loads the specified config file using the specified
  58.                                     character encoding
  59.   tidy_set_encoding($enc)           Sets the current character encoding for the document
  60.   tidy_save_config($file)           Saves the current config to $file
  61.   
  62.   
  63. Beyond these general-purpose API functions, Tidy also supports the following
  64. functions which are used to retrieve an object for document traversal:
  65.   
  66.   tidy_get_root()              Returns an object starting at the root of the
  67.                                     document
  68.   tidy_get_head()              Returns an object starting at the <HEAD> tag
  69.   tidy_get_html()              Returns an object starting at the <HTML> tag
  70.   tidy_get_body()              Returns an object starting at the <BODY> tag
  71.   
  72. All Navigation of the specified document is done via the PHP5 object constructs.
  73. There are two types of objects which Tidy can create. The first is TidyNode, which
  74. represents HTML Tags, Text, and more (see the TidyNode_Type Constants). The second
  75. is TidyAttr, which represents an attribute within an HTML tag (TidyNode). The
  76. functionality of these objects is represented by the following schema:
  77.  
  78. class TidyNode {
  79.  
  80.     public $name;               // name of node (i.e. HEAD)
  81.     public $value;              // value of node (everything between tags)
  82.     public $type;               // type of node (text, php, asp, etc.)
  83.     public $id;                 // id of node (i.e. TIDY_TAG_HEAD)
  84.     
  85.     public function attributes();            // an array of attributes (see TidyAttr)
  86.     public function children();           // an array of child nodes
  87.     
  88.     function has_siblings();    // any sibling nodes?
  89.     function has_children();    // any child nodes?
  90.        
  91.     function is_comment();      // is node a comment?
  92.     function is_xhtml();        // is document XHTML?
  93.     function is_xml();          // is document generic XML (not HTML/XHTML)
  94.     function is_text();         // is node text?
  95.     function is_html();         // is node an HTML tag?
  96.     
  97.     function is_jste();         // is jste block?
  98.     function is_asp();          // is Microsoft ASP block?
  99.     function is_php();          // is PHP block?
  100.     
  101.     function next();            // returns next node
  102.     function prev();            // returns prev node
  103.         
  104.     /* Searches for a particular attribute in the current node based
  105.        on node ID. If found returns a TidyAttr object for it */
  106.     function get_attr($attr_id);
  107.  
  108.     /*
  109. }
  110.  
  111. class TidyAttr {
  112.  
  113.     public $name;           // attribute name i.e. HREF
  114.     public $value;          // attribute value
  115.     public $id;             // attribute id i.e. TIDY_ATTR_HREF
  116.  
  117. }
  118.  
  119. Examples of using these objects to navigate the tree can be found in the examples/
  120. directory (I suggest looking at urlgrab.php and dumpit.php)
  121.  
  122. E-mail thoughts, suggestions, patches, etc. to <john@php.net>
  123.